Space Lua is a custom dialect and implementation of the Lua programming language, embedded in SilverBullet. It aims to be a largely complete Lua implementation, but adds a few non-standard features while remaining syntactically compatible with “real” Lua.
Each space-lua block has its own local scope. However, following Lua semantics, when functions and variables are not explicitly defined as local they will be available globally across your space. This means that the adder function above can be used in any other page.
Since there is a single global namespace, it is good practice to manually namespace functions using the following pattern:
Scripts are loaded in reverse priority order. When you set no priority (the default) your scripts will be run last.
The order used is determined by this query (also part of your Space Overview) page:
This means that the higher the priority, the earlier the script is loaded. That also means that if you want to override previously defined definitions you need to a set a lower priority (or in most cases: simply omit the priority comment).
Here are the conventions used by the Std library:
For example: 10 + 2 = ${adder(10, 2)} (Alt-click, or select to see the expression) is using the just defined adder function to this rather impressive calculation.
${query[[
from index.tag "page"
order by lastModified desc
select name
limit 3
]]}
To render a widget, call widget.new with any of the following keys:
To render a custom HTML-based widget, use the DOM API:
We can combine this with some Space Style to style it:
Now, let’s use it (try clicking):
${marquee "Finally, marqeeeeeee!"}
Oh boy, the times we live in!
Try it: ${widgets.commandButton("Hello World")}
Basics
In its essence, Space Lua adds two features to SilverBullet’s Markdown language:- Definitions: Code written in space-lua code blocks are enabled across your entire space.
- Expressions: The ${expression} syntax will Live Preview to its evaluated value.
Definitions
Space Lua definitions are defined in fenced code blocks, in this case with the space-lua language. As follows:-- adds two numbers
function adder(a, b)
return a + b
end
Each space-lua block has its own local scope. However, following Lua semantics, when functions and variables are not explicitly defined as local they will be available globally across your space. This means that the adder function above can be used in any other page.
Since there is a single global namespace, it is good practice to manually namespace functions using the following pattern:
-- This initializes the stuff variable with an empty table if it's not already defined
stuff = stuff or {}
function stuff.adder(a, b)
return a + b
end
Load order
It is possible to control load order of space lua scripts using the special -- priority: <number> comment in Lua code.Scripts are loaded in reverse priority order. When you set no priority (the default) your scripts will be run last.
The order used is determined by this query (also part of your Space Overview) page:
query[[
from index.tag "space-lua"
order by priority desc
]]
This means that the higher the priority, the earlier the script is loaded. That also means that if you want to override previously defined definitions you need to a set a lower priority (or in most cases: simply omit the priority comment).
Here are the conventions used by the Std library:
- priority: 100 for config definitions (schemas)
- priority: 50 for setting really core and root variables (like template.* APIs) that will be used by other scripts
- priority: 10: for standard library definitions that may be overriden (by scripts with lower priority)
note Tip
All your space-lua scripts are loaded on boot, to reload them without reloading the page, simply run the ${widgets.commandButton("System: Reload")} (Ctrl-Alt-r) command.
Expressions
A new syntax introduced with Space Lua is the ${lua expression} syntax that you can use in your pages. This syntax will Live Preview to the evaluation of that expression.For example: 10 + 2 = ${adder(10, 2)} (Alt-click, or select to see the expression) is using the just defined adder function to this rather impressive calculation.
Queries
Space Lua has a feature called Lua Integrated Query, which integrate SQL-like queries into Lua. Here’s a small example querying the last 3 modifies pages:${query[[
from index.tag "page"
order by lastModified desc
select name
limit 3
]]}
Widgets
The ${lua expression} syntax can be used to implement custom widgets. If the Lua expression evaluates to a simple string, it will live preview as that string rendered as markdown. However, if the expression returns a widget.new-generated result value, you can do some cooler stuff.To render a widget, call widget.new with any of the following keys:
- markdown: Renders the value as markdown
- html: Renders a HTML string as a widget. This is somewhat brittle. Therefore, it’s preferred to use the DOM API (see an example below).
- display: Render the value either inline or as a block (defaults to inline)
To render a custom HTML-based widget, use the DOM API:
function marquee(text)
return dom.marquee {
class = "my-marquee",
onclick = function()
editor.flashNotification "You clicked me"
end,
text
}
end
We can combine this with some Space Style to style it:
.my-marquee {
color: purple;
}Now, let’s use it (try clicking):
${marquee "Finally, marqeeeeeee!"}
Oh boy, the times we live in!
Commands
Custom commands can be defined using command#command.define(commandDef):command.define {
name = "Hello World",
run = function()
editor.flashNotification "Hello world!"
event.dispatch("my-custom-event", {name="Pete"})
end
}Try it: ${widgets.commandButton("Hello World")}
Slash commands
Custom slash commands can be defined using slashcommand#slashcommand.define(spec):slashcommand.define {
name = "hello",
run = function()
editor.insertAtCursor("Hello |^| world!", false, true)
end
}Event listeners
You can listen to events using event#event.listen(listenerDef):event.listen {
name = "my-custom-event";
run = function(e)
editor.flashNotification("Custom triggered: "
.. e.data.name)
end
}Space Lua Extensions
Space Lua introduces a few new features on top core Lua:- Lua Integrated Query, embedding a query language into Lua itself
- Thread locals
Thread locals
There's a magic _CTX global variable available from which you can access useful context-specific values. Currently the following keys are available:- _CTX.currentPage providing access (in the client only) to the currently open page (PageMeta object)
- _CTX._GLOBAL providing access to the global scope
API
Lua implementation notes
Space Lua is intended to be a more or less complete implementation of Lua 5.4. However, a few features are (still) missing:- goto and labels (not planned, goto considered harmful)
- coroutines (not planned, not useful in the SilverBullet context)
- _ENV (planned)
- Full metatable support (only partial now, planned)